<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>chmod</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<xref type="10" name="chmod"></xref>
<h4><a name = "tag_001_014_035">&nbsp;</a>NAME</h4><blockquote>
chmod - change the file modes
</blockquote><h4><a name = "tag_001_014_036">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

chmod <b>[</b>-R<b>] </b><i>mode file</i>...
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_037">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>chmod</i>
utility will change any or all of the file mode bits of the
file named by each
<i>file</i>
operand in the way specified by the
<i>mode</i>
operand.
<p>
It is implementation-dependent whether and how the
<i>chmod</i>
utility affects
any alternate or additional file access control mechanism (see
<b>file access permissions</b>
in
the <b>XBD</b> specification, <a href="../xbd/glossary.html"><b>Glossary</b>&nbsp;</a> )
being used for the specified file.
<p>
Only a process whose effective user ID matches the user ID of the file,
or a process with the appropriate privileges, will be permitted to
change the file mode bits of a file.
</blockquote><h4><a name = "tag_001_014_038">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>chmod</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
The following option is supported:
<dl compact>

<dt><b>-R</b>
<dd>Recursively change file mode bits.
For each
<i>file</i>
operand that names a directory,
<i>chmod</i>
will change the file mode bits of the directory and all files
in the file hierarchy below it.

</dl>
</blockquote><h4><a name = "tag_001_014_039">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>mode</i><dd>Represents the change to be made to
the file mode bits of each file named by one of the
<i>file</i>
operands; see the EXTENDED DESCRIPTION section.

<dt><i>file</i><dd>A pathname of a file whose file mode bits are to be modified.

</dl>
</blockquote><h4><a name = "tag_001_014_040">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_041">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_042">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>chmod</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_043">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_044">&nbsp;</a>STDOUT</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_045">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_046">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_047">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
The
<i>mode</i>
operand will be either a
<b>symbolic_mode</b>
expression
or a non-negative octal integer.
The
<b>symbolic_mode</b>
form is described by the grammar later in this section.
<p>
Each
<b>clause</b>
will specify an operation to be performed on the
current file mode bits of each
<i>file</i>.
The operations will be performed on each
<i>file</i>
in the order in which the
<b>clause</b>s
are specified.
<p>
The
<i>who</i>
symbols
u,
g
and
o
will specify the
<i>user ,</i>
<i>group</i>
and
<i>other</i>
parts of the file mode bits, respectively.
A
<i>who</i>
consisting of the symbol
a
will be equivalent to
<b>ugo</b>.
<p>
The
<i>perm</i>
symbols
r,
w
and
x
represent the
<i>read ,</i>
<i>write</i>
and
<i>execute/search</i>
portions of file mode bits, respectively.
The
<i>perm</i>
symbol
s
represent the
<i>set-user-ID-on-execution</i>
(when
<b>who</b>
contains or implies
u)
and
<i>set-group-ID-on-execution</i>
(when
<b>who</b>
contains or implies
g)
bits.
<p>
The
<b>perm</b>
symbol
X
represent the execute/search portion of the file
mode bits if the file is a directory or if the current (unmodified) file
mode bits have at least one of the execute bits (S_IXUSR, S_IXGRP or
S_IXOTH) set.
It will be ignored if the file is not a directory and
none of the execute bits are set in the current file mode bits.
<p>
The
<b>permcopy</b>
symbols
u,
g
and
o
represent the current
permissions associated with the user, group and other parts of
the file mode bits, respectively.
For the remainder of this section,
<b>perm</b>
refers to the
non-terminals
<b>perm</b>
and
<b>permcopy</b>
in the grammar.
<p>
If multiple
<b>actionlist</b>s
are grouped with a single
<b>wholist</b>
in the grammar, each
<b>actionlist</b>
will be applied in the order specified with that
<b>wholist</b>.
The
<b>op</b>
symbols represent the operation performed, as follows:
<dl compact>

<dt><b>+</b><dd>If
<b>perm</b>
is not specified, the + operation will not change the
file mode bits.

If
<b>who</b>
is not specified, the file mode bits represented by
<b>perm</b>
for the owner, group and other permissions, except for those
with corresponding bits in the file mode creation mask of the
invoking process, will be set.

Otherwise, the file mode bits represented by the specified
<b>who</b>
and
<b>perm</b>
values will be set.

<dt><b>-</b><dd>If
<b>perm</b>
is not specified, the "-" operation will not change the file mode bits.

If
<b>who</b>
is not specified, the file mode bits represented by
<b>perm</b>
for the owner, group and other permissions, except for those
with corresponding bits in the file mode creation mask of the
invoking process, will be cleared.

Otherwise, the file mode bits represented by the specified
<b>who</b>
and
<b>perm</b>
values will be cleared.

<dt><b>=</b><dd>Clear the file mode bits specified by the
<b>who</b>
value, or, if no
<b>who</b>
value is specified, all of the file mode bits specified in
this specification.

If
<b>perm</b>
is not specified, the = operation will make no further
modifications to the file mode bits.

If
<b>who</b>
is not specified, the file mode bits represented by
<b>perm</b>
for the owner, group and other permissions, except for those
with corresponding bits in the file mode creation mask of the
invoking process, will be set.

Otherwise, the file mode bits represented by the specified
<b>who</b>
and
<b>perm</b>
values will be set.

</dl>
<p>
When using the symbolic mode form on a regular file,
it is implementation-dependent whether or not:
<p>
<ul>
<p>
<li>
Requests to set the set-user-ID-on-execution or set-group-ID-on-execution
bit when all execute bits are currently clear and
none are being set are ignored.
<p>
<li>
Requests to clear all execute bits also clear the set-user-ID-on-execution
and set-group-ID-on-execution bits.
<p>
<li>
Requests to clear the set-user-ID-on-execution or set-group-ID-on-execution
bits when all execute bits are currently clear are ignored.
However, if the command
<i><a href="ls.html">ls</a></i>
<b>-l</b>
<i>file</i>
writes an
s
in the position indicating that the
set-user-ID-on-execution or set-group-ID-on-execution is set, the
commands
<i>chmod</i>
<b>u-s</b>
<i>file</i>
or
<i>chmod</i>
<b>g-s</b>
<i>file</i>,
respectively, will not be ignored.
<p>
</ul>
<p>
When using the symbolic mode form on other file types, it is
implementation-dependent whether or not requests to set or clear
the set-user-ID-on-execution or set-group-ID-on-execution bits
are honoured.
<p>
If the
<b>who</b>
symbol
o
is used in conjunction with the
<b>perm</b>
symbol
s
with no
other
<b>who</b>
symbols being specified, the set-user-ID-on-execution and
set-group-ID-on-execution
bits will not be modified.
It will not be an
error to specify the
<b>who</b>
symbol
o
in conjunction with the
<b>perm</b>
symbol
s.
<p>
For an octal integer
<i>mode</i>
operand, the file mode bits will be set absolutely.
<p>
For each bit set in the octal number, the corresponding
file permission bit shown in
the following table will be set;
all other file permission bits will be cleared.
For regular files, for
each bit set in the octal number corresponding to the
set-user-ID-on-execution or the set-group-ID-on-execution bits
shown in the following table will be set;
if these bits are not
set in the octal number, they will be cleared.
For other file
types, it is implementation-dependent whether or not requests to
set or clear the set-user-ID-on-execution or
set-group-ID-on-execution bits are honoured.
<pre>
<table  bordercolor=#000000 border=1<tr valign=top><th align=center><b>Octal</b>
<th align=left>Mode bit
<th align=center><b>Octal</b>
<th align=center><b>Mode bit</b>
<th align=left>Octal
<th align=center><b>Mode bit</b>
<th align=center><b>Octal</b>
<th align=left>Mode bit
<tr valign=top><td align=left>4000
<td align=left>S_ISUID
<td align=left>0400
<td align=left>S_IRUSR
<td align=left>0040
<td align=left>S_IRGRP
<td align=left>0004
<td align=left>S_IROTH
<tr valign=top><td align=left>2000
<td align=left>S_ISGID
<td align=left>0200
<td align=left>S_IWUSR
<td align=left>0020
<td align=left>S_IWGRP
<td align=left>0002
<td align=left>S_IWOTH
<tr valign=top><td align=left>&nbsp;
<td align=left>&nbsp;
<td align=left>0100
<td align=left>S_IXUSR
<td align=left>0010
<td align=left>S_IXGRP
<td align=left>0001
<td align=left>S_IXOTH
</table>
</pre>
<p>
When bits are set in the octal number other
than those listed in the table above, the behaviour is unspecified.
<h5><a name = "tag_001_014_047_001">&nbsp;</a>Grammar for chmod</h5>
The grammar and lexical conventions in this section describe the syntax
for the
<b>symbolic_mode</b>
operand.
The general conventions for this style of grammar are described in
<xref href=grammar></xref>.
A valid
<b>symbolic_mode</b>
can be represented
as the non-terminal symbol
<b>symbolic_mode</b>
in the grammar.
This formal syntax takes precedence over
the preceding text syntax description.
<p>
The lexical processing will be based entirely on single characters.
Implementations need not allow
blank characters
within the single argument being processed.
<p>
<pre>
<code>
%start             symbolic_mode
%%

symbolic_mode    : section
                 | symbolic_mode ',' section
                 ;

section          : actionlist
                 | wholist actionlist
                 ;

wholist          : who
                 | wholist who
                 ;

who              : 'u' | 'g' | 'o' | 'a'
                 ;

actionlist       : action
                 | actionlist action
                 ;

action           : op
                 | op permlist
                 | op permcopy
                 ;

permcopy         : 'u' | 'g' | 'o'
                 ;

op               : '+' | '-' | '='
                 ;

permlist         : perm
                 | perm permlist
                 ;

perm             : 'r' | 'w' | 'x' | 'X' | 's'
                 ;
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_048">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>The utility executed successfully and all requested changes were made.

<dt>&gt;0<dd>An error occurred.

</dl>
<br>
</blockquote><h4><a name = "tag_001_014_049">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
If, when invoked with the
<b>-R</b>
option,
<i>chmod</i>
attempts but fails to change
the mode of a particular file in a specified file hierarchy, it
will continue to process the remaining files in the hierarchy, affecting the
final exit status.
If
<i>chmod</i>
cannot read or search a directory within a
hierarchy, it will continue to process the other parts of the hierarchy
that are accessible.
</blockquote><h4><a name = "tag_001_014_050">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The references to octal modes are supported
because, although they are obsolescent in the ISO/IEC 9945-2:1993 standard,
XSI-conformant systems have committed to maintaining them
for portable applications until further notice.
<p>
Some implementations of the
<i>chmod</i>
utility change the mode of a
directory before the files in the directory when performing a recursive
(<b>-R</b>
option) change; others change the directory mode after the files in
the directory.
If an application tries to remove read or search permission for a
file hierarchy, the removal attempt will fail if the directory is changed
first; on the other hand, trying to re-enable permissions to a restricted
hierarchy will fail if directories are changed last.
Users should not try to make a
hierarchy inaccessible to themselves.
<p>
Some implementations of
<i>chmod</i>
never used the process'
<i>umask</i>
when changing modes; systems conformant with this specification do so when
<b>who</b>
is not specified.
Note the difference between:
<pre>
<code>
chmod a-w file
</code>
</pre>
which removes all write permissions, and:
<pre>
<code>
chmod -- -w file
</code>
</pre>
<br>
which removes write permissions that would be allowed if
<b>file</b>
was created
with the same
<i>umask.</i>
<p>
Portable applications
should never assume that they know how the
set-user-ID and set-group-ID bits on directories
will be interpreted.
<br>
</blockquote><h4><a name = "tag_001_014_051">&nbsp;</a>EXAMPLES</h4><blockquote>
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Mode</b>
<th align=center><b>Results</b>
<tr valign=top><td align=left><b>a+=</b>
<td align=left> Equivalent to clears all file mode bits. 
<tr valign=top><td align=left><b>go+-w</b>
<td align=left> Equivalent to clears group and other write bits. 
<tr valign=top><td align=left><b>g=o-w</b>
<td align=left> Equivalent to sets group bit to match other bits and then clears group write bit. 
<tr valign=top><td align=left><b>g-r+w</b>
<td align=left> Equivalent to clears group read bit and sets group write bit. 
<tr valign=top><td align=left><b>=g</b>
<td align=left>Sets owner bits to match group bits and sets other bits to match group bits
</table>
</pre>
</blockquote><h4><a name = "tag_001_014_052">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_053">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="ls.html">ls</a></i>,
<i><a href="umask.html">umask</a></i>,
the <b>XSH</b> specification description of
<i><a href="../xsh/chmod.html">chmod()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
